Filtering, pagination and sorting

Endpoints that return a collection share three query conventions: filter narrows the collection, page and limit split it into pages, and sort orders it. Which fields each endpoint accepts is listed on the endpoint's own page.

Filtering

Use the filter query parameter to return only part of a collection, such as the calls that started on one day.

Filter syntax

A filter is one or more conditions, wrapped in parentheses. A condition is a field, an operator, and a value:

upalpha    = "A" / "B" / "C" / "D" / "E" / "F" / "G" / "H" / "I" / "J" / "K" / "L" / "M" /
             "N" / "O" / "P" / "Q" / "R" / "S" / "T" / "U" / "V" / "W" / "X" / "Y" / "Z"
lowalpha   = "a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" / "i" / "j" / "k" / "l" / "m" /
             "n" / "o" / "p" / "q" / "r" / "s" / "t" / "u" / "v" / "w" / "x" / "y" / "z"
alpha      = lowalpha / upalpha
digit      = "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9"
hex        = "A" / "B" / "C" / "D" / "E" / "F" / "a" / "b" / "c" / "d" / "e" / "f" / digit
escaped    = "%" hex hex
val        = 1*( alpha / digit / escaped )
cond-field = val
cond-oper  = "=" / "!=" / ">" / "<" / ">=" / "<="
cond-value = val *( ";" val )
condition  = cond-field cond-oper cond-value
filter     = "(" condition *( "," condition ) ")"

These rules follow from the grammar:

• Separate conjunctive (AND) conditions with a comma: (id>7,id<12).
• Within one condition, separate disjunctive (OR) values with a semicolon: (id=7;12). This works with the = and != operators only.
• Escape non-alphanumeric characters in a value with URL escaping. Because the whole filter is escaped again when it is sent as a query parameter, characters inside a value end up double escaped: a space becomes %2520, not %20.
• A date-time value can be a date alone, YYYY-MM-DD, or a full RFC 3339 UTC timestamp, YYYY-MM-DDTHH:MM:SS.LLLZ. A date alone is read as 00:00:00.

Filter examples

Each row pairs a filter condition with the query string that carries it.

Condition	Query string
id=7;12 — equals 7 or 12	?filter=(id%3D7%3B12)
id>7,id<12 — above 7 and below 12	?filter=(id%3E7%2Cid%3C12)
id>7,id<12,id!=10 — above 7 and below 12, but not 10	?filter=(id%3E7%2Cid%3C12%2Cid!%3D10)
name=first%20last — a value containing a space, double escaped	?filter=(name%3Dfirst%2520last)
setupTime>=2022-04-26,setupTime<2022-04-27 — one day	?filter=(setupTime%3E%3D2022-04-26%2CsetupTime%3C2022-04-27)
setupTime>=2022-04-26T15:00:00.000Z,setupTime<2022-04-26T16:00:00.000Z — one hour	?filter=(setupTime%3E%3D2022-04-26T15%3A00%3A00.000Z%2CsetupTime%3C2022-04-26T16%3A00%3A00.000Z)

Free-text search

Endpoints that support free-text search accept it as a text field inside the filter, on its own or alongside other conditions:

Condition	Query string
text=some%20words	?filter=(text%3Dsome%2520words)
setupTime>=2022-04-26,setupTime<2022-04-27,text=some%20words	?filter=(setupTime%3E%3D2022-04-26%2CsetupTime%3C2022-04-27%2Ctext%3Dsome%2520words)

Pagination

GET requests on a collection accept two query parameters:

Parameter	Type	Description
limit	number	Maximum number of resources to include in the response. Each collection has its own default. The response may hold fewer resources than the limit.
page	number	Which page to return, where each page holds up to limit resources. Without it, only the first page is returned.

GET /api/v1/calls?page=1&limit=10

The response body carries a pages object describing where you are in the collection:

{
  "pages": {
    "size": 10,
    "total": 1,
    "current": 1,
    "totalElements": 1
  }
}

Property	Type	Description
size	number	Size of each page.
total	number	Total number of pages.
current	number	Current page number.
totalElements	number	Total number of elements across all pages.

Sorting

Use the sort query parameter to order the collection by a field:

Query string	Result
?sort=setupTime	Ascending by setupTime.
?sort=-setupTime	Descending — prefix the field with a minus sign.
?sort=successful&sort=-setupTime	By several fields — repeat the parameter.